<HTML>
<BODY BGCOLOR=white>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
NAME
     jsv_is_param, jsv_get_param,  jsv_add_param,  jsv_mod_param,
     jsv_del_param,      jsv_sub_is_param,     jsv_sub_get_param,
     jsv_sub_add_param,      jsv_sub_del_param,       jsv_is_env,
     jsv_get_env,    jsv_add_env,    jsv_mod_env,    jsv_del_env,
     jsv_accept,   jsv_correct,   jsv_reject,    jsv_reject_wait,
     jsv_show_params,         jsv_show_envs,        jsv_log_info,
     jsv_log_warning, jsv_log_error, jsv_main - Sun  Grid  Engine
     Job Submission Verifier Scripting Interface

SYNOPSIS
     jsv_clear_params();
     jsv_is_param(<I>param</I>_<I>name</I>);
     jsv_get_param(<I>param</I>_<I>name</I>);
     jsv_set_param(<I>param</I>_<I>name</I>, <I>param</I>_<I>value</I>);
     jsv_del_param(<I>param</I>_<I>name</I>);
     jsv_sub_is_param(<I>param</I>_<I>name</I>, <I>variable</I>_<I>name</I>);
     jsv_sub_get_param(<I>param</I>_<I>name</I>, <I>variable</I>_<I>name</I>);
     jsv_sub_add_param(<I>param</I>_<I>name</I>, <I>variable</I>_<I>name</I>, <I>variable</I>_<I>value</I>);
     jsv_sub_del_param(<I>param</I>_<I>name</I>, <I>variable</I>_<I>name</I>);

     jsv_clear_envs();
     jsv_is_env(<I>variable</I>_<I>name</I>);
     jsv_get_env(<I>variable</I>_<I>name</I>);
     jsv_add_env(<I>variable</I>_<I>name</I>, <I>variable</I>_<I>value</I>);
     jsv_mod_env(<I>variable</I>_<I>name</I>, <I>variable</I>_<I>value</I>);
     jsv_del_env(<I>variable</I>_<I>name</I>);

     jsv_accept(<I>message</I>);
     jsv_correct(<I>message</I>);
     jsv_reject(<I>message</I>);
     jsv_reject_wait(<I>message</I>);

     jsv_show_params();
     jsv_show_envs();
     jsv_log_info(<I>message</I>);
     jsv_log_warning(<I>message</I>);
     jsv_log_error(<I>message</I>);

     jsv_main();
     jsv_send_env();
     jsv_on_start();
     jsv_on_verify();

DESCRIPTION
     The functions documented here implement the server  side  of
     the  JSV protocol as it is described in the man page <B><A HREF="../htmlman1/jsv.html?pathrev=V62u5_TAG">jsv(1)</A></B>.
     These script functions are available in Bourne shell, TCL or
     Perl    scripts    after    sourcing/including   the   files
     jsv_inlcude.sh, jsv_include.tcl or JSV.pm.   The  files  and
     corresponding JSV script templates are located in the direc-
     tory $SGE_ROOT/util/resources/jsv.

  jsv_clear_params()
     This function clears all received job parameters  that  were
     stored during the last job verification process.

  jsv_clear_envs()
     This function clears all received job environment  variables
     that were stored during the last job verification process.

  jsv_show_params()
     A call of this function reports all known job parameters  to
     the  counterpart  of  this  script  (client or master daemon
     thread). This parameters will be reported as  info  messages
     and  appear  either in the stdout stream of the client or in
     the message file of the master process.

  jsv_show_envs()
     A call of this function reports all  known  job  environment
     variables  to the counterpart of this script (client or mas-
     ter daemon thread). They will be reported as  info  messages
     and appear in the stdout stream of the client or in the mes-
     sage file of the master process.

  jsv_is_param()
     This function returns whether or not a specific job  parame-
     ters is available for the job which is currently being veri-
     fied. Either the string <I>true</I> or <I>false</I> will be returned.  The
     availability/absence  of  a job parameter does not mean that
     the corresponding command line switch was used/not used.

     The following values are allowed for <I>param</I>_<I>name</I>. Correspond-
     ing  <I>qsub</I>/<I>qrsh</I>/<I>qsh</I>/...  switches  next to the parameter name
     are mentioned only if they are different  from  the  command
     line switches.

     Find additional information in <B><A HREF="../htmlman1/qsub.html?pathrev=V62u5_TAG">qsub(1)</A></B> man  page  describing
     the availability and value format. Job parameters written in
     capital letters are pseudo parameters. A  detailed  descrip-
     tion for them can be found in <B><A HREF="../htmlman1/jsv.html?pathrev=V62u5_TAG">jsv(1)</A></B>

        param_name              command line switch/description
        a
        ac                      combination of -ac, -sc, -dc
        ar
        A
        b
        c
        ckpt
        cwd
        display
        dl
        e
        h
        hold_jid
        hold_jid_ad
        i
        l_hard                  -l or -hard followed by -l
        l_soft                  -soft followed by -l
        j
        js
        m
        M
        masterq
        N
        notify
        now
        N
        o
        ot
        P
        pe
        q_hard                  -q or -hard followed by -q
        q_soft                  -soft followed by -q
        R
        r
        shell
        S
        t
        w
        wd
        CLIENT
        CONTEXT
        GROUP
        VERSION
        JOB_ID
        SCRIPT
        CMDARGS
        CMDARG&lt;i&gt;               where &lt;i&gt; is a nonnegative number
        USER

     The function  returns  the  string  <I>true</I>  if  the  parameter
     (<I>param</I>_<I>name</I>)  exists in the job currently being verified. If
     it does not exist <I>false</I> will be returned.

  jsv_get_param()
     This function returns the value of a specific job  parameter
     (<I>param</I>_<I>name</I>).

     This value is only available if the function  jsv_is_param()
     returns <I>true</I>. Otherwise an empty string is returned.

     Find a list of allowed parameter names in  the  section  for
     the function jsv_is_param().


  jsv_set_param()
     This function changes the job parameter (<I>param</I>_<I>name</I>) to  the
     value <I>param</I>_<I>value</I>.

     If <I>param</I>_<I>value</I> is an empty string then the corresponding job
     parameter   will   be   deleted   similar  to  the  function
     jsv_del_param(). As a result the job parameter is not avail-
     able  as  if  the  corresponding command line switch was not
     specified during job submission.

     For boolean parameters that only accept the values <I>yes</I> or <I>no</I>
     it is not allowed to pass an empty string as <I>param</I>_<I>value</I>.

     Also for the parameters <I>c</I> and <I>m</I> it is  not  allowed  to  use
     empty strings. Details can be found in <B><A HREF="../htmlman1/qsub.html?pathrev=V62u5_TAG">qsub(1)</A></B>.

  jsv_del_param()
     This function deletes the job parameter <I>param</I>_<I>name</I>.

     Find a list of allowed parameter names in  the  section  for
     the function jsv_is_param().

  jsv_sub_is_param()
     Some job parameters are  lists  that  can  contain  multiple
     variables with an optional value.

     This function returns <I>true</I> if a job parameters list contains
     a  variable  and  <I>false</I> otherwise. <I>false</I> might also indicate
     that the parameter list itself is  not  available.  Use  the
     function  jsv_is_param()  to  check if the parameter list is
     not available.

     The following parameters are  list  parameters.  The  second
     columns  describes  corresponding variable names to be used.
     The third column contains a dash (-) if there  is  no  value
     (<I>variable</I>_<I>value</I>)     allowed      when     the     functions
     jsv_sub_add_param() or it indicated that jsv_sub_get_param()
     will  return  always  an  empty  string. A question mark (?)
     shows that the value is optional.

        param_name        variable_name              variable_value
        ac                job context variable name
        hold_jid          job identifier             -
        l_hard            complex attribute name     ?
        l_soft            complex attribute name     ?
        M                 mail address               -
        masterq           cluster queue name or      -
                          queue instance name
        q_hard            cluster queue name or      -
                          queue instance name
        q_soft            cluster queue name or      -
                          queue instance name

  jsv_sub_get_param()
     Some job parameters are  lists  that  can  contain  multiple
     variables with an optional value.

     This   function   returns   the   value   of   a    variable
     (<I>variable</I>_<I>name</I>).   For  sub list elements that have no value
     an empty string will be returned.

     Find a list of  allowed  parameter  names  (<I>param</I>_<I>name</I>)  and
     variable  names (<I>variable</I>_<I>name</I>) in the section for the func-
     tion jsv_sub_is_param().

  jsv_sub_add_param()
     Some job parameters are list that can contain multiple vari-
     ables with an optional value.

     This function either adds a new variable with a new value or
     it modifies the value if the variable is already in the list
     parameter.  <I>variable</I>_<I>value</I> is optional. In  that  case,  the
     variable has no value.

     Find a list of  allowed  parameter  names  (<I>param</I>_<I>name</I>)  and
     variable  names (<I>variable</I>_<I>name</I>) in the section for the func-
     tion jsv_sub_is_param().

  jsv_sub_del_param()
     Some job parameters are lists  which  can  contain  multiple
     variables with an optional value.

     This function deletes  a  variable  (<I>variable</I>_<I>name</I>)  and  if
     available the corresponding value. If (<I>variable</I>_<I>name</I>) is not
     available in the job parameter  then  the  command  will  be
     ignored.

     Find a list of  allowed  parameter  names  (<I>param</I>_<I>name</I>)  and
     variable names (<I>variable</I>_<I>name</I> ) in the section for the func-
     tion jsv_sub_is_param().

  jsv_is_env()
     If the function returns <I>true</I>, then the job environment vari-
     able with the name <I>variable</I>_<I>name</I> exists in the job currently
     being verified and jsv_get_env() can be used to retrieve the
     value of that variable.  If the function returns <I>false</I>, then
     the job environment variable (<I>variable</I>_<I>name</I>) does not exist.

  jsv_get_env()
     This function returns the value of a job  environment  vari-
     able (<I>variable</I>_<I>name</I>).

     This variable has to be passed with the  <I>qsub</I>  command  line
     switch  -<I>v</I>  or  -<I>V</I> and it has to be enabled that environment
     variable data is passed to JSV scripts. Environment variable
     data is passed when the function jsv_send_env() is called in
     the callback function jsv_on_start().

     If the variable does not exist or  if  environment  variable
     information  is  not  available then an empty string will be
     returned.

  jsv_add_env()
     This function adds an additional environment variable to the
     set  of  variables that will exported to the job, when it is
     started.  As a result the <I>variable</I>_<I>name</I>  and  <I>variable</I>_<I>value</I>
     become  available,  as  if the -v or -V was specified during
     job submission.

     <I>variable</I>_<I>value</I> is optional. If  there  is  an  empty  string
     passed then the variable is defined without value.

     If <I>variable</I>_<I>name</I> already exists in the set of  job  environ-
     ment   variables,  then  the  corresponding  value  will  be
     replaced by <I>variable</I>_<I>value</I>, as if the function jsv_mod_env()
     was  used.  If  an empty string is passed then the old value
     will be deleted.

     To delete a environment variable the function  jsv_del_env()
     has to be used.

  jsv_mod_env()
     This function modifies an existing environment variable that
     is  in  the set of variables which will exported to the job,
     when it is started.  As  a  result,  the  <I>variable</I>_<I>name</I>  and
     <I>variable</I>_<I>value</I>  will  be  available  as  if the -v or -V was
     specified during job submission.

     <I>variable</I>_<I>value</I> is optional. If  there  is  an  empty  string
     passed then the variable is defined without value.

     If <I>variable</I>_<I>name</I> does not already exist in the  set  of  job
     environment variables, then the corresponding name and value
     will be added as if the function jsv_add_env() was used.

     To  delete  a  environment  variable,   use   the   function
     jsv_del_env().

  jsv_del_env()
     This   function   removes   a   job   environment   variable
     (<I>variable</I>_<I>name</I>)  from  the  set  of  variables  that will be
     exported to the job, when it is started.

     If <I>variable</I>_<I>name</I> does not already exists in the set  of  job
     environment variables then the command is ignored.


     To  change  the  value  of  a  variable  use  the   function
     jsv_mod_env()   to  add  a  new  value,  call  the  function
     jsv_add_env().

  jsv_accept()
     This function can only be used in jsv_on_verify(). After  it
     has  been called, the function jsv_on_verify() has to return
     immediately.

     A call to this function  indicates  that  the  job  that  is
     currently  being  verified should be accepted as it was ini-
     tially provided. All job  modifications that might have been
     applied  in jsv_on_verify() before this function was called,
     are then ignored.

     Instead of calling jsv_accept() in jsv_on_verify() also  the
     functions  jsv_correct(),  jsv_reject() or jsv_reject_wait()
     can be called, but only one of these functions can  be  used
     at a time.

  jsv_correct()
     This function can only be used in jsv_on_verify(). After  it
     has  been called, the function jsv_on_verify() has to return
     immediately.

     A call to this function  indicates  that  the  job  that  is
     currently being verified has to be modified before it can be
     accepted. All job parameter modifications that  were  previ-
     ously  applied  will  be  committed  and  the  job  will  be
     accepted. "Accept" in that case  means  that  the  job  will
     either  be  passed to the next JSV instance for modification
     or that it is passed to that component in the master  daemon
     that  adds  it  to  the  master data store when the last JSV
     instance has verified the job.

     Instead of calling  jsv_correct()  in  jsv_on_verify(),  the
     functions  jsv_accept(),  jsv_reject()  or jsv_reject_wait()
     can be called, but only one of these functions can be used.

  jsv_reject()
     This function can only be used in jsv_on_verify(). After  it
     has  been  called the function jsv_on_verify() has to return
     immediately.

     The job that is currently being verified will  be  rejected.
     <I>message</I>  will be passed to the client application that tried
     to submit the job. Commandline clients like <I>qsub</I> will  print
     that  message  to stdout to inform the user that the submis-
     sion has failed.

     jsv_reject_wait() should be called if the user  may  try  to
     submit  the  job again. jsv_reject_wait() indicates that the
     verification process might be successful in the future.

     Instead of calling jsv_reject() in jsv_on_verify() also  the
     functions  jsv_accept(),  jsv_correct() or jsv_reject_wait()
     can be also called, but only one of these functions  can  be
     used.

  jsv_reject_wait()
     This function can only be used in jsv_on_verify(). After  it
     has  been  called the function jsv_on_verify() has to return
     immediately.

     The job which is currently verified will be  rejected.  <I>mes-</I>
     <I>sage</I> will be passed to the client application, that tries to
     submit the job. Commandline clients  like  <I>qsub</I>  will  print
     that  message  to stdout to inform the user that the submis-
     sion has failed.

     This function should be called if the user who tries to sub-
     mit  the  job  might  have a chance to submit the job later.
     jsv_reject indicates that the  verified  job  will  also  be
     rejected in future.

     Instead of calling jsv_reject_wait() in jsv_on_verify()  the
     functions jsv_accept(), jsv_correct() or jsv_reject() can be
     also called, but only one of these functions can be used.

  jsv_log_info()
     This function sends an info <I>message</I> to the client or  master
     daemon instance that started the JSV script.

     For client JSVs, this means that  the  command  line  client
     will  get the information and print it to the stdout stream.
     Server JSVs will print that message as an  info  message  to
     the master daemon message file.

     If <I>message</I> is missing then and empty line will be printed.

  jsv_log_warning()
     This function sends a warning <I>message</I> to the client or  mas-
     ter daemon instance that started the JSV script.

     For client JSVs, this means that  the  command  line  client
     will  get the information and print it to the stdout stream.
     Server JSVs will print that message as an warning message to
     the master daemon message file.

     If <I>message</I> is missing then and empty line will be printed.

  jsv_log_error()
     This function sends an error <I>message</I> to the client or master
     daemon instance that started the JSV script.
     For client JSVs, this means that  the  command  line  client
     will  get the information and print it to the stdout stream.
     Server JSVs will print that message as an error  message  to
     the master daemon message file.

     If <I>message</I> is missing then and empty line will be printed.

  jsv_send_env()
     This function can only be used in jsv_on_start(). If  it  is
     used  there,  then  the  job environment information will be
     available in  jsv_on_verify()  for  the  next  job  that  is
     scheduled to be verified.

     This   function   must   be   called   for   the   functions
     jsv_show_envs(),  jsv_is_env(), jsv_get_env(), jsv_add_env()
     and jsv_mod_env() to behave correctly.

     Job environments might become very big (10K and more).  This
     will  slow  down  the  executing component (submit client or
     master daemon thread).  For  this  reason,  job  environment
     information is not passed to JSV scripts by default.

     Please note also that the data in the job environment  can't
     be  verified by Grid Engine and might therefore contain data
     which could be misinterpreted in the script environment  and
     cause security issues.

  jsv_main()
     This function has to be  called  an  main  function  in  JSV
     scripts.  It  implements  the  JSV protocol and performs the
     communication with client and server components which  might
     start JSV scripts.

     This function does not return immediately. It  returns  only
     when the "QUIT" command is send by the client or server com-
     ponent.

     During the communication with client and server  components,
     this  function  triggers two callback functions for each job
     that should be verified. First jsv_on_start() and  later  on
     jsv_on_verify().

     jsv_on_start() can be used to initialize certain things that
     might    be    needed    for   the   verification   process.
     jsv_on_verify() does the verification process itself.

     The function jsv_send_env() can be called in  jsv_on_start()
     so that the job environment is available in jsv_on_verify().

     The following function can only be used in  jsv_on_verify().
     Simple   job   parameters  can  be  accessed/modified  with:
     jsv_is_param,     jsv_get_param,      jsv_set_param      and
     jsv_del_param.

     List  based   job   parameters   can   be   accessed   with:
     jsv_sub_is_param,  jsv_sub_get_param,  jsv_sub_add_param and
     jsv_sub_del_param

     If the environment  was  requested  with  jsv_send_env()  in
     jsv_on_start() then the environment can be accessed/modified
     with  the  following  commands:   jsv_is_env,   jsv_get_env,
     jsv_add_env, jsv_mod_env and jsv_del_env

     Jobs  can   be   accepted/rejected   with   the   following:
     jsv_accept, jsv_correct, jsv_reject and jsv_reject_wait.

     The following functions send messages to  the  calling  com-
     ponent of a JSV that will either appear on the stdout stream
     of the client or in the master message file. This  is  espe-
     cially  useful  when  new  JSV  scripts  should  be  tested:
     jsv_show_params,        jsv_show_envs,         jsv_log_info,
     jsv_log_warning and jsv_log_error

  jsv_on_start()
     This is a callback function that has to be  defined  by  the
     creator  of  a JSV script.  It is called for every job short
     time before the verification process of a job starts.

     Within this function jsv_send_env can be called  to  request
     job environment information for the next job is scheduled to
     be verified.

     After this function returns jsv_on_verify() will be  called.
     This function does there verification process itself.

  jsv_on_verify()
     This is a callback function that has to be  defined  by  the
     creator  of  a  JSV  script.  It is called for every job and
     when it returns  a  the  job  will  either  be  accepted  or
     rejected.  Find  implementation  examples  in  the directory
     $SGE_ROOT/util/resources/jsv.

     The logic of this function completely depends on the creator
     of this function. The creator has only to take care that one
     of     the     functions     jsv_accept(),     jsv_reject(),
     jsv_reject_wait()  or  jsv_correct()  is  called  before the
     function returns.

EXAMPLES
     Find in the table below the returned values for  the  "*is*"
     and "*get*" functions when following job is submitted:

           qsub -l mem=1G,mem2=200M ...

           function call                    returned value
           -----------------------------    -----------------
           jsv_is_param(l_hard)             "true"
           jsv_get_param(l_hard)            "mem=1G,mem2=200M"
           jsv_sub_is_param(l_hard,mem)     "true"
           jsv_sub_get_param(l_hard,mem)    "1G"
           jsv_sub_get_param(l_hard,mem3)   "false"
           jsv_sub_get_param(l_hard,mem3)   ""


SEE ALSO
     <B><A HREF="../htmlman1/sge_intro.html?pathrev=V62u5_TAG">sge_intro(1)</A></B>,  <B><A HREF="../htmlman1/jsv.html?pathrev=V62u5_TAG">jsv(1)</A></B>,   <B><A HREF="../htmlman1/qalter.html?pathrev=V62u5_TAG">qalter(1)</A></B>,   <B><A HREF="../htmlman1/qlogin.html?pathrev=V62u5_TAG">qlogin(1)</A></B>,   <B><A HREF="../htmlman1/qmake.html?pathrev=V62u5_TAG">qmake(1)</A></B>,
     <B><A HREF="../htmlman1/qrsh.html?pathrev=V62u5_TAG">qrsh(1)</A></B>, <B><A HREF="../htmlman1/qsh.html?pathrev=V62u5_TAG">qsh(1)</A></B>, <B><A HREF="../htmlman1/qsub.html?pathrev=V62u5_TAG">qsub(1)</A></B>, <B><A HREF="../htmlman1/qtcsh.html?pathrev=V62u5_TAG">qtcsh(1)</A></B>,

COPYRIGHT
     See <B><A HREF="../htmlman1/sge_intro.html?pathrev=V62u5_TAG">sge_intro(1)</A></B> for a full statement of rights and  permis-
     sions.



































</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
